<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>LDAP user authentication | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'ldap-realm.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/ldap-realm.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/ldap-realm.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/ldap-realm.html" rel="nofollow" target="_blank">../en/ldap-realm.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="setting-up-authentication.html">User authentication</a></span>
»
<span class="breadcrumb-node">LDAP user authentication</span>
</div>
<div class="navheader">
<span class="prev">
<a href="file-realm.html">« File-based user authentication</a>
</span>
<span class="next">
<a href="native-realm.html">Native user authentication »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="ldap-realm"></a>LDAP user authentication<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/ldap-realm.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>
<p>You can configure the Elastic Stack security features to communicate with a
Lightweight Directory Access Protocol (LDAP) server to authenticate users. See
<a class="xref" href="ldap-realm.html#ldap-realm-configuration" title="Configuring an LDAP realm">Configuring an LDAP realm</a>.</p>
<p>LDAP stores users and groups hierarchically, similar to the way folders are
grouped in a file system. An LDAP directory’s hierarchy is built from containers
such as the <em>organizational unit</em> (<code class="literal">ou</code>), <em>organization</em> (<code class="literal">o</code>), and
<em>domain controller</em> (<code class="literal">dc</code>).</p>
<p>The path to an entry is a <em>Distinguished Name</em> (DN) that uniquely identifies a
user or group. User and group names typically have attributes such as a
<em>common name</em> (<code class="literal">cn</code>) or <em>unique ID</em> (<code class="literal">uid</code>). A DN is specified as a string,
for example  <code class="literal">"cn=admin,dc=example,dc=com"</code> (white spaces are ignored).</p>
<p>The <code class="literal">ldap</code> realm supports two modes of operation, a user search mode
and a mode with specific templates for user DNs.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="mapping-roles-ldap"></a>Mapping LDAP groups to roles<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/ldap-realm.asciidoc">edit</a>
</h3>
</div></div></div>
<p>An integral part of a realm authentication process is to resolve the roles
associated with the authenticated user. Roles define the privileges a user has
in the cluster.</p>
<p>Since with the <code class="literal">ldap</code> realm the users are managed externally in the LDAP server,
the expectation is that their roles are managed there as well. In fact, LDAP
supports the notion of groups, which often represent user roles for different
systems in the organization.</p>
<p>The <code class="literal">ldap</code> realm enables you to map LDAP users to roles via their LDAP
groups or other metadata. This role mapping can be configured via the
<a class="xref" href="security-api-put-role-mapping.html" title="Create or update role mappings API">add role mapping API</a> or by using a
file stored on each node. When a user authenticates with LDAP, the privileges
for that user are the union of all privileges defined by the roles to which
the user is mapped.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ldap-realm-configuration"></a>Configuring an LDAP realm<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/ldap-realm.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To integrate with LDAP, you configure an <code class="literal">ldap</code> realm and map LDAP groups to
user roles.</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Determine which mode you want to use. The <code class="literal">ldap</code> realm supports two modes of
operation, a user search mode and a mode with specific templates for user DNs.</p>
<p>LDAP user search is the most common mode of operation. In this mode, a specific
user with permission to search the LDAP directory is used to search for the DN
of the authenticating user based on the provided username and an LDAP attribute.
Once found, the user is authenticated by attempting to bind to the LDAP server
using the found DN and the provided password.</p>
<p>If your LDAP environment uses a few specific standard naming conditions for
users, you can use user DN templates to configure the realm. The advantage of
this method is that a search does not have to be performed to find the user DN.
However, multiple bind operations might be needed to find the correct user DN.</p>
</li>
<li class="listitem">
<p>To configure an <code class="literal">ldap</code> realm with user search:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Add a realm configuration of to <code class="literal">elasticsearch.yml</code> under the
<code class="literal">xpack.security.authc.realms.ldap</code> namespace. At a minimum, you must specify
the <code class="literal">url</code> of the LDAP server, and set <code class="literal">user_search.base_dn</code> to the container DN
where the users are searched for.
If you are configuring multiple realms, you should also explicitly set the
<code class="literal">order</code> attribute to control the order in which the realms are consulted during
authentication. See <a class="xref" href="security-settings.html#ref-ldap-settings" title="LDAP realm settings">LDAP realm settings</a> for all of the options you can set for
an <code class="literal">ldap</code> realm.</p>
<p>For example, the following snippet shows an LDAP realm configured with a user search:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack:
  security:
    authc:
      realms:
        ldap:
          ldap1:
            order: 0
            url: "ldaps://ldap.example.com:636"
            bind_dn: "cn=ldapuser, ou=users, o=services, dc=example, dc=com"
            user_search:
              base_dn: "dc=example,dc=com"
              filter: "(cn={0})"
            group_search:
              base_dn: "dc=example,dc=com"
            files:
              role_mapping: "ES_PATH_CONF/role_mapping.yml"
            unmapped_groups_as_roles: false</pre>
</div>
<p>The password for the <code class="literal">bind_dn</code> user should be configured by adding the appropriate
<code class="literal">secure_bind_password</code> setting to the Elasticsearch keystore.
For example, the following command adds the password for the example realm above:</p>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">bin/elasticsearch-keystore add \
xpack.security.authc.realms.ldap.ldap1.secure_bind_password</pre>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>When you configure realms in <code class="literal">elasticsearch.yml</code>, only the
realms you specify are used for authentication. If you also want to use the
<code class="literal">native</code> or <code class="literal">file</code> realms, you must include them in the realm chain.</p>
</div>
</div>
</li>
</ol>
</div>
</li>
<li class="listitem">
<p>To configure an <code class="literal">ldap</code> realm with user DN templates:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Add a realm configuration to <code class="literal">elasticsearch.yml</code> in the
<code class="literal">xpack.security.authc.realms.ldap</code> namespace. At a minimum, you must specify
the <code class="literal">url</code> of the LDAP server, and specify at least one template with the
<code class="literal">user_dn_templates</code> option. If you are configuring multiple realms, you should
also explicitly set the <code class="literal">order</code> attribute to control the order in which the
realms are consulted during authentication.
See <a class="xref" href="security-settings.html#ref-ldap-settings" title="LDAP realm settings">LDAP realm settings</a> for all of the options you can set for an <code class="literal">ldap</code> realm.</p>
<p>For example, the following snippet shows an LDAP realm configured with user DN
templates:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack:
  security:
    authc:
      realms:
        ldap:
          ldap1:
            order: 0
            url: "ldaps://ldap.example.com:636"
            user_dn_templates:
              - "cn={0}, ou=users, o=marketing, dc=example, dc=com"
              - "cn={0}, ou=users, o=engineering, dc=example, dc=com"
            group_search:
              base_dn: "dc=example,dc=com"
            files:
              role_mapping: "/mnt/elasticsearch/group_to_role_mapping.yml"
            unmapped_groups_as_roles: false</pre>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">bind_dn</code> setting is not used in template mode.
All LDAP operations run as the authenticating user.</p>
</div>
</div>
</li>
</ol>
</div>
</li>
<li class="listitem">
<p>(Optional) Configure how the security features interact with multiple LDAP
servers.</p>
<p>The <code class="literal">load_balance.type</code> setting can be used at the realm level. The Elasticsearch
security features support both failover and load balancing modes of operation.
See <a class="xref" href="security-settings.html#ref-ldap-settings" title="LDAP realm settings">LDAP realm settings</a>.</p>
</li>
<li class="listitem">
(Optional) To protect passwords,
<a class="xref" href="configuring-tls.html#tls-ldap" title="Encrypting communications between Elasticsearch and LDAP">encrypt communications between Elasticsearch and the LDAP server</a>.
</li>
<li class="listitem">
Restart Elasticsearch.
</li>
<li class="listitem">
<p>Map LDAP groups to roles.</p>
<p>The <code class="literal">ldap</code> realm enables you to map LDAP users to roles via their LDAP
groups, or other metadata. This role mapping can be configured via the
<a class="xref" href="security-api-put-role-mapping.html" title="Create or update role mappings API">add role mapping API</a> or by using a file stored
on each node. When a user authenticates with LDAP, the privileges
for that user are the union of all privileges defined by the roles to which
the user is mapped.</p>
<p>Within a mapping definition, you specify groups using their distinguished
names. For example, the following mapping configuration maps the LDAP
<code class="literal">admins</code> group to both the <code class="literal">monitoring</code> and <code class="literal">user</code> roles, and maps the
<code class="literal">users</code> group to the <code class="literal">user</code> role.</p>
<p>Configured via the role-mapping API:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/role_mapping/admins
{
  "roles" : [ "monitoring" , "user" ],
  "rules" : { "field" : {
    "groups" : "cn=admins,dc=example,dc=com" <a id="CO472-1"></a><i class="conum" data-value="1"></i>
  } },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1221.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO472-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The LDAP distinguished name (DN) of the <code class="literal">admins</code> group.</p>
</td>
</tr>
</table>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "field" : {
    "groups" : "cn=users,dc=example,dc=com" <a id="CO473-1"></a><i class="conum" data-value="1"></i>
  } },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1222.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO473-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The LDAP distinguished name (DN) of the <code class="literal">users</code> group.</p>
</td>
</tr>
</table>
</div>
<p>Or, alternatively, configured via the role-mapping file:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">monitoring: <a id="CO474-1"></a><i class="conum" data-value="1"></i>
  - "cn=admins,dc=example,dc=com" <a id="CO474-2"></a><i class="conum" data-value="2"></i>
user:
  - "cn=users,dc=example,dc=com" <a id="CO474-3"></a><i class="conum" data-value="3"></i>
  - "cn=admins,dc=example,dc=com"</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO474-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The name of the mapped role.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO474-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The LDAP distinguished name (DN) of the <code class="literal">admins</code> group.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO474-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>The LDAP distinguished name (DN) of the <code class="literal">users</code> group.</p>
</td>
</tr>
</table>
</div>
<p>For more information, see
<a class="xref" href="ldap-realm.html#mapping-roles-ldap" title="Mapping LDAP groups to roles">Mapping LDAP groups to roles</a> and <a class="xref" href="mapping-roles.html" title="Mapping users and groups to roles">Mapping users and groups to roles</a>.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The LDAP realm supports
<a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">authorization realms</a> as an
alternative to role mapping.</p>
</div>
</div>
</li>
<li class="listitem">
<p>(Optional) Configure the <code class="literal">metadata</code> setting on the LDAP realm to include extra
fields in the user’s metadata.</p>
<p>By default, <code class="literal">ldap_dn</code> and <code class="literal">ldap_groups</code> are populated in the user’s metadata.
For more information, see
<a class="xref" href="ldap-realm.html#ldap-user-metadata" title="User metadata in LDAP realms">User metadata in LDAP realms</a>.</p>
<p>The example below includes the user’s common name (<code class="literal">cn</code>) as an additional
field in their metadata.</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">xpack:
  security:
    authc:
      realms:
        ldap:
          ldap1:
            metadata: cn</pre>
</div>
</li>
<li class="listitem">
Set up SSL to encrypt communications between Elasticsearch and LDAP. See <a class="xref" href="configuring-tls.html#tls-ldap" title="Encrypting communications between Elasticsearch and LDAP">Encrypting communications between Elasticsearch and LDAP</a>.
</li>
</ol>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ldap-user-metadata"></a>User metadata in LDAP realms<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/ldap-realm.asciidoc">edit</a>
</h3>
</div></div></div>
<p>When a user is authenticated via an LDAP realm, the following properties are
populated in the user’s <em>metadata</em>:</p>
<div class="informaltable">
<table border="1" cellpadding="4px">
<colgroup>
<col class="col_1">
<col class="col_2">
</colgroup>
<tbody>
<tr>
<td align="left" valign="top"><p>Field</p></td>
<td align="left" valign="top"><p>Description</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">ldap_dn</code></p></td>
<td align="left" valign="top"><p>The distinguished name of the user.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">ldap_groups</code></p></td>
<td align="left" valign="top"><p>The distinguished name of each of the groups that were
                        resolved for the user (regardless of whether those
                        groups were mapped to a role).</p></td>
</tr>
</tbody>
</table>
</div>
<p>This metadata is returned in the
<a href="security-api-authenticate.html" class="ulink" target="_top">authenticate API</a>, and can be used with
<a class="xref" href="field-and-document-access-control.html#templating-role-query" title="Templating a role query">templated queries</a> in roles.</p>
<p>Additional fields can be included in the user’s metadata by  configuring
the <code class="literal">metadata</code> setting on the LDAP realm. This metadata is available for use
with the <a class="xref" href="mapping-roles.html#mapping-roles-api" title="Using the role mapping API">role mapping API</a> or in
<a class="xref" href="field-and-document-access-control.html#templating-role-query" title="Templating a role query">templated role queries</a>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="ldap-load-balancing"></a>Load balancing and failover<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/ldap-realm.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The <code class="literal">load_balance.type</code> setting can be used at the realm level to configure how
the security features should interact with multiple LDAP servers. The
security features support both failover and load balancing modes of operation.</p>
<p>See <a class="xref" href="security-settings.html#load-balancing" title="Load balancing and failover">Load balancing and failover</a>.</p>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="file-realm.html">« File-based user authentication</a>
</span>
<span class="next">
<a href="native-realm.html">Native user authentication »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>